//
//  DMUserConsent.h
//  DualMediationSDK
//
//  Created by AI Assistant
//  Copyright © 2024 YourCompany. All rights reserved.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * 用户同意类型
 */
typedef NS_ENUM(NSUInteger, DMConsentType) {
    DMConsentTypeATT = 0,        // App Tracking Transparency
    DMConsentTypeGDPR,           // General Data Protection Regulation
    DMConsentTypeCCPA,           // California Consumer Privacy Act
    DMConsentTypeUMP,            // User Messaging Platform
    DMConsentTypeCOPPA           // Children's Online Privacy Protection Act
};

/**
 * 同意状态
 */
typedef NS_ENUM(NSUInteger, DMConsentStatus) {
    DMConsentStatusUnknown = 0,
    DMConsentStatusGranted,
    DMConsentStatusDenied,
    DMConsentStatusNotRequired
};

/**
 * DM用户同意模型
 * 
 * 核心特性：
 * 1. 多种隐私法规支持
 * 2. 同意状态持久化
 * 3. 同意变更追踪
 * 4. 地域适用性判断
 */
@interface DMUserConsent : NSObject <NSCoding, NSSecureCoding, NSCopying>

#pragma mark - Basic Properties

/**
 * 用户ID（可选）
 */
@property (nonatomic, strong, nullable) NSString *userId;

/**
 * 创建时间
 */
@property (nonatomic, strong, readonly) NSDate *createdAt;

/**
 * 最后更新时间
 */
@property (nonatomic, strong, readonly) NSDate *updatedAt;

/**
 * 版本号
 */
@property (nonatomic, strong, readonly) NSString *version;

#pragma mark - Consent Status

/**
 * ATT同意状态（App Tracking Transparency）
 */
@property (nonatomic, assign) DMConsentStatus attStatus;

/**
 * GDPR同意状态
 */
@property (nonatomic, assign) DMConsentStatus gdprStatus;

/**
 * CCPA同意状态
 */
@property (nonatomic, assign) DMConsentStatus ccpaStatus;

/**
 * UMP同意状态
 */
@property (nonatomic, assign) DMConsentStatus umpStatus;

/**
 * COPPA同意状态
 */
@property (nonatomic, assign) DMConsentStatus coppaStatus;

#pragma mark - Detailed Consent Information

/**
 * 是否同意数据收集
 */
@property (nonatomic, assign) BOOL canCollectData;

/**
 * 是否同意个性化广告
 */
@property (nonatomic, assign) BOOL canShowPersonalizedAds;

/**
 * 是否同意数据分享
 */
@property (nonatomic, assign) BOOL canShareData;

/**
 * 是否同意分析数据收集
 */
@property (nonatomic, assign) BOOL canCollectAnalytics;

/**
 * 是否同意跨应用追踪
 */
@property (nonatomic, assign) BOOL canTrackAcrossApps;

#pragma mark - GDPR Specific Properties

/**
 * GDPR是否适用
 */
@property (nonatomic, assign) BOOL gdprApplies;

/**
 * GDPR同意字符串
 */
@property (nonatomic, strong, nullable) NSString *gdprConsentString;

/**
 * GDPR同意日期
 */
@property (nonatomic, strong, nullable) NSDate *gdprConsentDate;

#pragma mark - CCPA Specific Properties

/**
 * CCPA是否适用
 */
@property (nonatomic, assign) BOOL ccpaApplies;

/**
 * CCPA选择退出日期
 */
@property (nonatomic, strong, nullable) NSDate *ccpaOptOutDate;

#pragma mark - Geographic Information

/**
 * 用户国家代码
 */
@property (nonatomic, strong, nullable) NSString *countryCode;

/**
 * 用户州/省代码
 */
@property (nonatomic, strong, nullable) NSString *stateCode;

/**
 * 是否在GDPR管辖区域
 */
@property (nonatomic, assign) BOOL isInGDPRRegion;

/**
 * 是否在CCPA管辖区域
 */
@property (nonatomic, assign) BOOL isInCCPARegion;

#pragma mark - User Age Information

/**
 * 用户年龄（可选）
 */
@property (nonatomic, strong, nullable) NSNumber *userAge;

/**
 * 是否为儿童用户
 */
@property (nonatomic, assign) BOOL isChildUser;

/**
 * 是否需要家长同意
 */
@property (nonatomic, assign) BOOL requiresParentalConsent;

#pragma mark - Consent History

/**
 * 同意变更历史
 */
@property (nonatomic, strong, readonly) NSArray<NSDictionary *> *consentHistory;

#pragma mark - Initialization

/**
 * 创建默认用户同意对象
 */
+ (instancetype)defaultConsent;

/**
 * 根据地区创建用户同意对象
 * @param countryCode 国家代码
 * @param stateCode 州/省代码（可选）
 */
+ (instancetype)consentForCountry:(NSString *)countryCode state:(nullable NSString *)stateCode;

#pragma mark - Consent Management

/**
 * 设置特定类型的同意状态
 * @param status 同意状态
 * @param type 同意类型
 */
- (void)setConsentStatus:(DMConsentStatus)status forType:(DMConsentType)type;

/**
 * 获取特定类型的同意状态
 * @param type 同意类型
 */
- (DMConsentStatus)getConsentStatusForType:(DMConsentType)type;

/**
 * 检查是否已获得所有必要的同意
 */
- (BOOL)hasRequiredConsents;

/**
 * 检查是否可以展示广告
 */
- (BOOL)canShowAds;

/**
 * 检查是否可以展示个性化广告
 */
- (BOOL)canShowPersonalizedAds;

/**
 * 检查是否可以收集用户数据
 */
- (BOOL)canCollectUserData;

#pragma mark - Validation

/**
 * 验证同意信息的有效性
 */
- (BOOL)isValid;

/**
 * 获取验证错误信息
 */
- (nullable NSArray<NSString *> *)getValidationErrors;

#pragma mark - Persistence

/**
 * 保存到本地
 */
- (BOOL)saveToLocalStorage;

/**
 * 从本地加载
 */
+ (nullable instancetype)loadFromLocalStorage;

/**
 * 清除本地存储的同意信息
 */
+ (void)clearLocalStorage;

#pragma mark - Export/Import

/**
 * 导出为字典
 */
- (NSDictionary *)toDictionary;

/**
 * 从字典创建
 * @param dictionary 字典数据
 */
+ (nullable instancetype)fromDictionary:(NSDictionary *)dictionary;

/**
 * 导出为JSON字符串
 */
- (nullable NSString *)toJSONString;

/**
 * 从JSON字符串创建
 * @param jsonString JSON字符串
 */
+ (nullable instancetype)fromJSONString:(NSString *)jsonString;

#pragma mark - Utilities

/**
 * 将同意类型转换为字符串
 * @param type 同意类型
 */
+ (NSString *)stringForConsentType:(DMConsentType)type;

/**
 * 将同意状态转换为字符串
 * @param status 同意状态
 */
+ (NSString *)stringForConsentStatus:(DMConsentStatus)status;

/**
 * 将字符串转换为同意类型
 * @param typeString 类型字符串
 */
+ (DMConsentType)consentTypeForString:(NSString *)typeString;

/**
 * 将字符串转换为同意状态
 * @param statusString 状态字符串
 */
+ (DMConsentStatus)consentStatusForString:(NSString *)statusString;

/**
 * 检查国家是否需要GDPR合规
 * @param countryCode 国家代码
 */
+ (BOOL)isGDPRApplicableForCountry:(NSString *)countryCode;

/**
 * 检查地区是否需要CCPA合规
 * @param countryCode 国家代码
 * @param stateCode 州代码
 */
+ (BOOL)isCCPAApplicableForCountry:(NSString *)countryCode state:(nullable NSString *)stateCode;

@end

NS_ASSUME_NONNULL_END